home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / memory.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  4.8 KB  |  150 lines
  1. dopus5.library/AllocMemH                             dopus5.library/AllocMemH
  2.  
  3.     NAME
  4.         AllocMemH - allocate memory using pooling routines
  5.  
  6.     SYNOPSIS
  7.         AllocMemH(handle, size)
  8.                     A0     D0
  9.  
  10.         void *AllocMemH(APTR, ULONG);
  11.  
  12.     FUNCTION
  13.         This function allows you to allocate a chunk of memory. The type of
  14.         memory allocated was specified when the memory handle was created.
  15.         The size of the allocation is tracked automatically (similar to
  16.         AllocVec).
  17.  
  18.         You can actually use this function with a NULL memory handle - in this
  19.         case, the function performs much like AllocVec(). This disadvantage
  20.         to this is that you are unable to specify the type of memory you need
  21.         (the default is MEMF_ANY|MEMF_CLEAR). Memory allocated in this way can
  22.         obviously not be tracked, and you must FreeMemH() each allocation
  23.         individually.
  24.  
  25.     INPUTS
  26.         handle - memory handle (from NewMemHandle())
  27.         size - the amount of memory to allocate
  28.  
  29.     RESULT
  30.         Returns a pointer to the memory block for you to use, or NULL if
  31.         the request could not be satisfied.
  32.  
  33.     SEE ALSO
  34.         NewMemHandle(), FreeMemH()
  35.  
  36. dopus5.library/ClearMemHandle                   dopus5.library/ClearMemHandle
  37.  
  38.     NAME
  39.         ClearMemHandle - free all memory allocated via a handle
  40.  
  41.     SYNOPSIS
  42.         ClearMemHandle(handle)
  43.                          A0
  44.  
  45.         void ClearMemHandle(APTR);
  46.  
  47.     FUNCTION
  48.         This function frees all memory that has been allocated with
  49.         AllocMemH() via the specified handle. The memory handle itself
  50.         remains intact.
  51.  
  52.     INPUTS
  53.         handle - memory handle (from NewMemHandle())
  54.  
  55.     SEE ALSO
  56.         NewMemHandle(), AllocMemH(), FreeMemHandle()
  57.  
  58. dopus5.library/FreeMemH                               dopus5.library/FreeMemH
  59.  
  60.     NAME
  61.         FreeMemH - free memory allocated with AllocMemH()
  62.  
  63.     SYNOPSIS
  64.         FreeMemH(memory)
  65.                    A0
  66.  
  67.         void FreeMemH(APTR);
  68.  
  69.     FUNCTION
  70.         This function frees an individual memory chunk that was allocated
  71.         using AllocMemH().
  72.  
  73.     INPUTS
  74.         memory - memory address returned from AllocMemH()
  75.  
  76.     SEE ALSO
  77.         NewMemHandle(), AllocMemH()
  78.  
  79. dopus5.library/FreeMemHandle                     dopus5.library/FreeMemHandle
  80.  
  81.     NAME
  82.         FreeMemHandle - free a memory handle completely
  83.  
  84.     SYNOPSIS
  85.         FreeMemHandle(handle)
  86.                         A0
  87.  
  88.         void FreeMemHandle(APTR);
  89.  
  90.     FUNCTION
  91.         This function frees all memory that was allocated using the specified
  92.         handle, and then frees the handle itself.
  93.  
  94.     INPUTS
  95.         handle - memory handle from NewMemHandle()
  96.  
  97.     SEE ALSO
  98.         NewMemHandle(), ClearMemHandle()
  99.  
  100. dopus5.library/NewMemHandle                       dopus5.library/NewMemHandle
  101.  
  102.     NAME
  103.         NewMemHandle - allocate a new memory handle
  104.  
  105.     SYNOPSIS
  106.         NewMemHandle(puddle_size, thresh_size, type)
  107.                          D0            D1       D2
  108.  
  109.         APTR NewMemHandle(ULONG, ULONG, ULONG);
  110.  
  111.     FUNCTION
  112.         This function allocates a new memory handle, to enable easy access to
  113.         memory pooling and tracking functions.
  114.  
  115.         If you wish to use the OS memory pooling routines, specify a puddle
  116.         and a threshhold size for the memory pool. If you do not specify
  117.         these, the memory handle will use ordinary memory allocations and
  118.         keep track of these via a linked list. A linked list will also be
  119.         used if the creation of a memory pool fails for any reason.
  120.  
  121.         You must specify the type of memory you want when you create the
  122.         handle. All memory allocated with this handle will be of the requested
  123.         type (ie you can not mix fast and chip memory within the same handle).
  124.         The normal MEMF_ flags are used for this, with the following notes:
  125.  
  126.           - If MEMF_CLEAR is specified, the AllocMemH() routine clears the
  127.             memory itself (as the OS pooling routines do not support this).
  128.  
  129.           - If MEMF_PUBLIC is specified, it indicates that you want the memory
  130.             handle to be shareable between tasks, and the allocation routines
  131.             will use semaphore locking when accessing the handle.
  132.  
  133.         The dopus5.library is linked with the standalone memory pool routines,
  134.         and therefore these routines work under OS37 as well as OS39.
  135.  
  136.     INPUTS
  137.         puddle_size - size of puddles to use for pooling, or 0 for no pools
  138.         thresh_size - allocation threshhold size for pooling
  139.         type - type of memory to allocate
  140.  
  141.     RESULT
  142.         Returns a memory handle for use with the other memory functions, or
  143.         NULL for failure.
  144.  
  145.     SEE ALSO
  146.         AllocMemH(), ClearMemHandle(), FreeMemH(), FreeMemHandle(),
  147.         exec.library/AllocPooled(), exec.library/FreePooled(),
  148.         exec.library/CreatePool(), exec.library/DeletePool()
  149.  
  150.